EnigmA Amiga Run 1997 October/EnigmA AMIGA RUN 22 (1997)(G.R. Edizioni)(IT)[!][issue 1997-10 & 11][EAR-CD VI].iso/earcd/util1/adoc.lha/ADocEnglish.doc

Text File | 1997-05-24 | 22KB | 502 lines

                              ADoc - User's Manual





AboutThisDoc

          This manual describes release 5.00 of the utility ADoc. This program
  is Copyrigth ©1990-1997 by Denis GOUNELLE. Any commercial usage  or  selling
  without author's written authorization is strictly forbidden. You  can  copy
  and spread this program under the following conditions:

        - all the files are provided
        - the files are not modified in any way
        - you don't charge more than $6 for copy fee

          In spite of several tests, no warranty is made  that  there  are  no
  errors in ADoc. YOU USE THIS PROGRAM AT YOUR OWN RISK. In no event will I be
  liable for any damage, direct or indirect, resulting of the use of ADoc.

Foreword

          ADoc  is  an  utility  that  allows  you  to  visualize  "hypertext"
  documents. If you want to know what it means and to see what  ADoc  can  do,
  just click twice on  the word that follows : Explanation.

          Criticisms and suggestions will always be welcomed. Write to:

                               M. GOUNELLE Denis
                              27, rue Jules GUESDE
                            45400 FLEURY-LES-AUBRAIS
                                     FRANCE

                         [e-mail]

Explanation

       CONGRATULATIONS ! You've just understood how it worked !

  When you double-clicked on a single word in the text, ADoc has searched  the
  text associated to this word, in the documentation file, and  opened  a  new
  window to show you this text.

  What makes ADoc different from other programs of this type :

    - you can double-click on any word in the text, and ADoc will  search  for
      it (no more trouble because  the  document's  author  has  forgotten  an
      hypertext link !).

    - this implies that there is no need to  define  hypertext  links  in  the
      document (no more headaches for  the  author,  who  had  to  define  and
      maintain theses links in all the document !)

    - ADoc displays several windows at the same time (unless you ask  him  not
      to do so) and handles several document files at the same time.

    - ADoc can use straight files in the AutoDoc and AmigaGuide format.

    - ADoc has a lot of  little  tricks  and  useful  functions,  like  string
      searching in all the opened files, an AREXX port, and so on... (read the
      documentation, this time !)

Installation

          ADoc can be used on any Amiga computer under release 2.04  (V36)  or
  greater of the operating system.

          ADoc is now localized, so it  can  adapt  itself  to  your  favorite
  language. All you have to do is to copy  the  good  catalog  file  into  the
  directory corresponding to your  language.  For  exemple,  if  your  default
  language   is    french,    copy    the    "français.catalog"    into    the
  "SYS:Locale/Catalogs/Français" directory, under the name "ADoc.catalog."

ADocFileFormat

          ADoc works on documentation files, combined with a keyword (this one
  is named "term" in this doc). Every doc file has an index file  that  allows
  to access the wanted terms nearly immediately. (Note :  as  a  result,  each
  time you change a doc file, you'll have to rebuild  its  index  file.)  When
  ADoc is running, only is loaded in memory the index file. The name  of  this
  index file will be the doc file name plus an ".index" suffix.

          You can create your doc files with your favourite text editor; these
  files consist of a series of definitions and each definition has a syntax as
  follows :

                  term
                          text line 1
                          text line 2

                          etc...

                          text line n

          At first, consider that the first two lines of a doc file have to be
  empty (or in extreme circumstancies begin with a space or a tab  character).
  The first character of each term must be at column 1 and the text lines must
  begin with a space or a tab character. Empty lines are allowed.

          One term can't be more than 32 character long and can't contain  any
  blanks or tabs : valid  characters  are  upper  or  lower  letters,  digits,
  underline, and accented letters (ASCII codes between 192 and 253).  However,
  if needed, you can extend this character set (see below AdvancedConcepts).
          The term amount for each file as well as the text  line  amount  for
  each term are limited only by the available memory on your system).

          A text line can't be more than 256 characters. In order to bring out
  some parts of your text, you can use the following ANSI sequences :

                  ESC[1m  boldface on
                  ESC[3m  italics on
                  ESC[4m  underline on
                  ESC[22m boldface off
                  ESC[23m italics off
                  ESC[24m underline off
                  ESC[0m  normal character set

RunningADocfromCLI

  ADoc can be run from Workbench or from  the  CLI.  From  the  CLI,  you  can
  specify the following arguments :

  PUBSCREEN name
      Asks ADoc to use the given public screen. By default, ADoc opens  a  new
      custom screen, sized like the Workbench screen. screen.

  REXXPORT name
      Specifies  the  name  of  the  AREXX  port  to  open  (will  be  put  to
      upper-case). By default, the port's name is "ADOC_REXX".

  ICONNAME title
      Specifies the name of the icon, when ADoc is iconified.

  OPTIONS MAKEIDX|QUICK|AREXX|ONEWINDOW
      Specifies program's options.

      MAKEIDX
          Tells ADoc the only operation to perform  is  to  create  the  index
          files.

      QUICK
          Asks ADoc not to display a text combined to the "AboutThisDoc" term,
          when starting. Usually, each time ADoc opens a file,  it  looks  for
          the "AboutThisDoc" term in this file, and then, if this one  exists,
          displays the corresponding text.

      AREXX
          Asks ADoc to go in AREXX mode. More information on how to  use  ADoc
          with AREXX in TheAREXXMode section below.

      ONEWINDOW
          Asks ADoc to open only one window at a time.

  FONT name
      Asks ADoc to use the given font rather than the default text font.  Name
      must take the form <FontName><SizeY>, for ex. "topaz8". ADoc is able  to
      use any non proportional font.
      If the given font name is "REQUEST", ADoc will open a font requester  so
      that you can select the font to use.

  CASE YES|NO
      Asks ADoc if it must  differentiate  lower  and  upper  characters  when
      processing files. This only will concern files whose name is given after
      this option.

  SORT YES|NO
      Asks ADoc if it must sort the indexes of files whose name  is  specified
      after this option.

  TABSIZE n
      Tells the tab size for the files whose  name  is  specified  after  this
      option. Default size is 8.

  Any other argument will be considered as a doc file name to be used. You can
  specify several files, by separating their names by spaces  or  commas  (for
  ex. "ADoc file1 file2" or "ADoc file1,file2"). You can mix  file  names  and
  options but let us remember that FONT, CASE, SORT, and TABSIZE options  only
  concern files you specified after these options.

          ADoc will open files in this given order. Unless you indicate a full
  path, firstly files will be looked for in the current directory, then in the
  "ADOC:" one. If you specify a directory name instead of file name, ADoc will
  open all the files in  this  directory  (apart  from  ".info"  and  ".index"
  files).

RunningADocFromWorkbench

  From Workbench, you can inwoke ADoc in several ways :

    - by  double-clicking  on  its  icon  (then  ADoc  will  use  the  default
      documentation file)
    - by double-clicking on one file icon having ADoc as default  tool  (field
      "DEFAULT TOOL")
    - by clicking on icons of several files, holding down the SHIFT  key,  and
      double-clicking on the ADoc icon.

  In all these cases, ADoc starts by looking into "TOOL TYPES"  field  of  the
  program icon; this one may contain :

      PUBSCREEN=name
      REXXPORT=name
      ICONNAME=title
      OPTIONS=[MAKEIDX|QUICK|AREXX|ONEWINDOW]
      FONT=name
      TABSIZE=n
      SORT=YES|NO
      CASE=YES|NO

  For more information on these options, see the  RunningADocfromCLI  section.
  Note option names must be separated by a "|" sign.  After  that,  ADoc  will
  open the doc files you specified; it will open them  as  it  does  from  CLI
  except it examines the "TOOL TYPES" field  of  each  icon.  This  field  may
  contain :

      FONT=nom
      TABSIZE=n
      SORT=YES|NO
      CASE=YES|NO

  For  more  information  about  these  options,  see  the  RunningADocfromCLI
  section. Note these options only will concern the file corresponding to  the
  icon.

StartingADoc

          As explained above, ADoc starts by opening the specified file(s). If
  you didn't  specified any file to open, ADoc will  look  if  the  "ADocFile"
  variable is defined :  if so, it's value is used as a  file  name.  You  can
  specify several file names in  the "ADocFile" variable, just as from command
  line (for example: setenv ADocFile  "exec.doc dos.doc").

          Then, ADoc attempts as well to open the index file corresponding  to
  each doc file. If ADoc can't find the index file, it will  offer  to  create
  it. If you refuse, this doc file will not be usable but,  in  spite  of  it,
  ADoc will try to open the other files.
          If ADoc detects a doc file was changed after an index  was  created,
  it will offer to  update the index file. If you refuse, in spite of it,  the
  doc file will be opened but  ADoc may have some  troubles  later  with  this
  file (if it's content has changed). Note  the date of index file creation is
  stored in the index file itself.

          Once all files are opened, ADoc will display a requester : this  one
  indicates either the term list of the sole opened file, or the list  of  the
  opened  files.  We'll  describe  how  to   use   this   requester   in   the
  TheTermRequester section.

TheTermRequester

          A term can be pointed out by a mouse click on it. Now this  term  is
  displayed at the bottom of the requester. If you click a second time on  it,
  the requester is switched off  and  ADoc  displays  in  a  window  the  text
  corresponding to that term. We'll describe  how  to  use  these  windows  in
  HowToManageWindows section.

          To choose a term, you can use the keyboard too.  If  you  press  any
  key, the key letter will be added to the current "prefix"  (displayed  in  a
  rectangle below the term list), and ADoc will display the list starting from
  the first term that begins with this prefix. ADoc will complete this  prefix
  as far as possible. If you  press  the  <BACKSPACE>  key,  the  last  prefix
  character will be deleted and the list will be updated too. If you press the
  <RETURN> key, ADoc will display the text corresponding  to  the  first  term
  that begins with this prefix. Note ADoc will  not  differentiate  upper  and
  lower letters when the current file is indicated after a CASE=NO option.

          You can close  the  requester  without  selecting  a  term  both  by
  pressing the <ESC> key and by clicking in the close  gadget  either.  If  no
  window is open at this time, the program will abort (except  if  running  in
  AREXX mode).

          In fact, a term requester can allow you to select from  among  three
  lists : the term list of the current file, the list of the opened files  (if
  you have several opened files) and the list of terms that ADoc found  during
  the previous search operation (provided a search was made  before,  see  the
  Search section below).
          To switch from a list to another, press the <TAB> key. When the file
  list is displayed  and  you  select  a  file  in  this  list,  ADoc  returns
  automatically to the term list and displays the list of terms in that  file.

          The term requester has a menu with the following options :

          Open term       see TheProjectMenu below
          Search          see the Search section below
          Iconify         see the TheProjectMenu below
          Quit            this one allows to quit ADoc.

          The term  requester  uses  the  font  specified  in  the  last  FONT
  argument. So, if you want to use a different font for  this  requester,  you
  just have to append a FONT argument as the last argument.

HowToManageWindows

          When you  select  a  term,  ADoc  opens  a  window  to  display  the
  corresponding text. The window height is dependent on the  amount  of  lines
  ADoc must display. If there are too many lines, only the first page will  be
  displayed. Use the scroller at the right of the window to scroll this  text.

          By default, these windows have standard close,  dragging,  back  and
  front, and sizing gadgets. Each window has  three  menus  too  :  there  are
  "Project",  "Tools"  and  "Options"  menus  (I'll  describe  these  ones  in
  TheProjectMenu, TheToolsMenu and TheOptionsMenu sections, below).

          Finally, note ADoc recognize the following keys :

          ESC             closes the current window
          UP              scrolls one line up
          DOWN            scrolls one line down
          SHIFT-UP        scrolls one page up
          SHIFT-DOWN      scrolls one page down
          ALT-UP          go to the first page
          ALT-DOWN        go to the last page
          CTRL-UP         shows the previous term
          CTRL-DOWN       shows the next term

          When you click on a word, this one will be displayed in a  different
  colour. If you click again on the same word, ADoc will  automatically  start
  searching for the corresponding term in  all  open  files.  If  this  fails,
  screen flashes, otherwise a new window will be brought up.

          All term windows (and the term requester as well)  are  declared  as
  "AppWindows" (application windows). This mean that you can drop  Workbench's
  icons on these windows : the file(s) corresponding to these  icons  will  be
  scanned, and added to the opened files list.

TheProjectMenu

  Open file
      Allow to open an additional doc file. A file requester is brought up  so
      that you can specify what a file must be opened.

  Other term
      Bring up the term requester (see above TheTermRequester).

  Find
      Allow to start a search operation (see the Search section)

  Iconify
      Leave ADoc sleeping : all the windows will be switched off and then ADoc
      will open an icon on the Workbench's screen.  For  "awaking"  ADoc,  you
      just have to double-click on this icon : all the windows will be brought
      back.
      The icon will be the same as the program's  one  :  if  you  start  ADoc
      twice, from two different directories, containing different icons,  then
      each program will have a different icon.
      The icon will be declared as an "AppIcon" (application icon). This  mean
      that you can drop Workbench's icons on it : the file(s) corresponding to
      these icons will be scanned, and added to the opened files list.

  About...
      Display some informations about ADoc.

  Quit
      Allow to quit ADoc (asks you to confirm it).


TheToolsMenu

  Print
      Print the text of the current window. Note : the possible ANSI sequences
      will be correctly interpreted by the printer.

  Save as
      Save the text of the current window. Note : the possible ANSI  sequences
      will not be written to the file.

  Close all
      Allow to close all the windows at the same time.

TheOptionsMenu

  One window
      If this option is selected, ADoc will open only one window at a time.

Search

          ADoc can search for a string into :

  - the current term (when you select the "Find" menu item of a term  window).
    In this case, if you have selected a word in a term window, this word will
    be taken as the default value for the string to find.
  - all the terms of a file (when you select the "Find"  menu  item  when  the
    term requester  shows a file's term list)
  - all the terms of all the files (when you select the "Find" menu item  when
    the term requester show's the file list).

          In the first case,  once  the  search  is  completed,  the  window's
  content will be redrawn and any occurence will be put  in  bold  characters.
  The display is also moved so the line  with the first occurence will  be  at
  the top of the window.

          In the two other cases, a requester appears so you  can  follow  the
  search progress. The  "Abort" gadget of this requester allows you  to  break
  this search. As soon as the search  finished, screen will flash if  no  term
  was found. Otherwise, the term requester  will  be   switched  on  and  will
  display the list of found terms. That list is sorted, and  kept  in   memory
  until you stard a new search.

AdvancedConcepts

          In your documentation files, you  can  define  aliases,  that  is  a
  manner to associate  a same text to several terms, without having to  repeat
  the  text  several  times.  An   application  of  aliases   could   be   the
  documentation of  a  function  library  :  often  you  will  define  several
  functions together. With aliases, you can allow access to the definition  by
  the name of each function, but the text is defined only once.
          An alias definition follow the syntax:

          name1 alias name2

  The first character of "name2" must, as  for  any  term  definition,  be  at
  column one. There must be at least one space or tabulation between the three
  words. The word "alias" must be in lower case characters. The effect of such
  a definition is that when the user will ask to get the  "name1"  term,  ADoc
  will automatically display the "name2" term instead. Aliases appear  in  the
  term requester, and in the search function. You must be aware that there  is
  *NO* recursivity check between aliases !

                              --------------------

          ADoc can combine automatically several doc  files.  For  that,  it's
  enough to specify the name of file(s) to be combined, in the first  line  of
  file which you want associate them with. If this line  is  empty  or  begins
  with a space or tab, its contents will be ignored. File  names  have  to  be
  separated by spaces or commas. You can indicate a directory  name;  in  this
  case all the files of that directory will  be  opened  (except  ".info"  and
  ".index" files).
          Unless you indicate a full path, firstly files will be looked for in
  the directory of the calling file, then in the "ADOC:" directory.

                              --------------------

          To extend the character set you can use in a term,  it's  enough  to
  specify additional characters in the second line of your doc file.  If  this
  line is empty or begins with a space or tab, its contents will  be  ignored.
  Otherwise, all characters of that line (up to first  space,  tab,  slash  or
  form feed) will be added to the default character set. Note  this  character
  set extension only will concern that file.

TheAREXXMode

          ADoc always  opens  a  compatible  AREXX  port,  named  "ADOC_REXX".
  Messages on this port can take the following forms :

          QUIT            quits ADoc
          HIDE            iconifies ADoc
          SHOW            "wakes up" ADoc if it is iconified
          REQUEST         brings up the term requester
          TOFRONT         put ADoc screen in front of all screens
          TOBACK          put ADoc screen in back of all screens
          FIND term       start searching for a given term,  and  display  the
                          corresponding text if it is found
          OPEN file       allows to open one or several  files  while  running
                          ADoc
          CLOSEALL        closes any opened window

          Here is an example asking for help for the term "alias" :

          /* Ask for help for "alias" */
          ADDRESS "ADoc_rexx"
          "FIND alias"
          IF RC = 10 THEN SAY "not found !"

          If you launch ADoc with the option AREXX, the program operation will
  be quite different : once ADoc opened the doc file(s), it will not switch on
  the term requester but will wait for messages on  the  AREXX  port  (or  for
  CTRL-C to abort it). Moreover, when the last  window  will  be  closed,  the
  program will not end itself but go back waiting for AREXX messages.

AutoDoc_files_support

          ADoc can recognize and use files in the AutoDocs format.  Any  known
  variant of this file format is supported.

AmigaGuide_files_support

          ADoc can recognize and use files in the AmigaGuide format.  As  ADoc
  doesn't handle spaces  in  term  names,  they  are  replaced  by  underscore
  characters. Links within text  are  displayed  in  boldface.  As  names  are
  truncated to 32 characters, some links may fail.

          The @TAB et @FONT commands  (both  global  and  local),  the  @TITLE
  command, font style changes, external links, the escape character ('\')  are
  automatically handled.

          Unless the "QUICK" option has been  specified  at  program  startup,
  ADoc will automatically display the "MAIN" node when opening the file.

History

  v5.00, 06-Apr-97, 75108 bytes

    o Rewritten from scratch, in C++, using the SAS/C 6.57
    o New GUI using the "gadtools.library"
    o Can use any public screen
    o Can use a different font for each opened file
    o New iconification handling
    o Better support of AutoDoc and AmigaGuide files
    o All the windows are "AppWindow"s
    o Show the progression of index creation, of string search